Skip to main content

Local Development with the OIDC Toolkit

Overview​

The OIDC Toolkit provides a local development environment for building and testing OpenID Connect (OIDC) Single Sign-On integrations. It simulates the Candescent platform's OIDC flow, allowing you to develop and validate your integration before connecting to QA or production environments.

To setup the OIDC Toolkit, refer to the instructions in the README file.

What You Can Do​

  • Set up a complete OIDC Identity Provider locally.
  • Generate test client credentials (client_id, client_secret).
  • Download metadata and JWK files compatible with Candescent's format.
  • Execute the full authorization code flow.
  • Validate ID tokens and extract user claims.
  • Run automated E2E tests to verify your integration.
When to Use the Toolkit

Use the OIDC Toolkit during initial development to build and debug your OIDC client implementation. Once your integration works locally, proceed to QA validation with your Candescent PM.

Using the Toolkit​

1. Generate Client Credentials​

When the homepage loads, the toolkit automatically generates:

FieldDescription
Client IDPublic identifier for your OIDC client
Client SecretSecret key for token exchange
Credential Expiration

Credentials expire after 15 minutes and auto-regenerate. The page refreshes automatically.

2. Download Configuration Files​

Click the buttons to download:

FilePurposeUse In Your App
MetadataOIDC discovery documentConfigure endpoints, scopes
JWKRSA public keyValidate ID token signatures

3. Configure Your Integration​

Enter the required parameters:

ParameterDescriptionExample
Init URLYour app's SSO entry pointhttp://localhost:3000/sso/init
Callback HostOAuth redirect URI basehttp://localhost:3000/callback

Example Configuration:

If your application runs on localhost:3000, you might configure:

Init URL:      http://localhost:3000/auth/sso/start
Callback Host: http://localhost:3000/auth/callback
Testing with the Toolkit

For quick testing without a real app, you can use the toolkit's own URLs:

  • Init URL: http://localhost:8000
  • Callback Host: http://localhost:8000

This lets you test the OIDC flow end-to-end without building your own callback handler first.

4. Choose Display Mode​

ModeUse Case
Open in IframeEmbedded authentication experience
Open in new tabStandard redirect-based flow

For Iframe mode, also configure:

  • Unique ID - Identifies the Iframe session.
  • Display Width (%) - Controls Iframe width.
  • Permissions - Camera/microphone access (if needed).

5. Execute the OIDC Flow​

  1. Click Submit to save your configuration.
  2. Click Start OIDC SSO to initiate the flow.
  3. The toolkit simulates user authentication.
  4. Your callback receives the authorization code.
  5. Exchange the code for tokens.

Toolkit Endpoints​

The toolkit exposes endpoints that mirror Candescent's OIDC implementation:

Authorization Endpoint​

GET http://localhost:9000/api/auth/authorize

Parameters:

ParameterRequiredDescription
client_idYesFrom toolkit homepage
response_typeYesMust be code
scopeYesMust include openid
redirect_uriYesYour callback URL
stateRecommendedCSRF protection token

Example:

http://localhost:9000/api/auth/authorize?
  client_id=YOUR_CLIENT_ID
  &response_type=code
  &scope=openid
  &redirect_uri=https://yourapp.com/callback
  &state=random_state_value

Token Endpoint​

POST http://localhost:9000/api/auth/token

Headers:

Authorization: Basic <base64(client_id:client_secret)>
Content-Type: application/json

Body:

{
  "code": "AUTHORIZATION_CODE"
}

Response:

{
  "id_token": "eyJhbGciOiJSUzI1NiIs...",
  "access_token": "abc123...",
  "token_type": "Bearer",
  "expires_in": 900
}
Production Format

In production, the token endpoint uses application/x-www-form-urlencoded format instead of JSON. See the Technical Reference for production examples.

Validating Your Integration​

Manual Validation​

  1. Decode your ID token at jwt.io.
  2. Verify the signature using the downloaded JWK.
  3. Check all required claims are present and valid.

Automated Validation​

The toolkit includes E2E tests to validate your integration:

  1. Complete steps 1-4 above (configure and run the OIDC flow).
  2. Navigate to the OIDC Validator page (link in top-right).
  3. Click Run Validator.
  4. Review the test results.

Available Reports:

ReportFormatPurpose
e2e-report.htmlHTMLHuman-readable test results
jest-e2e.xmlJUnit XMLCI/CD integration

Export Configuration​

After successful validation:

  1. Click Publish OIDC Setting.
  2. Download oidcConfig.json.
  3. Use this configuration as a reference when connecting to Candescent environments.

Configuration Reference​

Port Configuration​

Edit sample-web-app/config.json:

{
  "frontendPort": 8000,
  "backendPort": 9000
}

Token Expiration​

Edit sample-web-app/backend/src/ssoConfig/sso-config.json:

{
  "auth_code_expires_in": 900,
  "access_token_expires_in": 900,
  "id_token_expires_in": 900
}

Values are in seconds (900 = 15 minutes).

Differences from Production​

The toolkit simulates Candescent's OIDC flow, but some differences exist:

AspectToolkitProduction
Authorization URLlocalhost:9000/api/auth/authorizeFI-specific domain
Token URLlocalhost:9000/api/auth/tokenapi.candescent.com/.../token
Token Request FormatJSON bodyapplication/x-www-form-urlencoded
User AuthenticationSimulated (automatic)Real FI login page
CredentialsAuto-generated, 15-min expiryPM-provided, 90-day rotation
JWKSDownloaded filePM-provided file
Transition to Production

Once your integration works with the toolkit, contact your Candescent PM to begin QA validation with production-like credentials and endpoints.

Troubleshooting​

IssueCauseSolution
Credentials expired15-minute TTLRefresh the page or wait for auto-refresh
Port already in useAnother service runningEdit sample-web-app/config.json to change ports
Token validation failsJWK mismatchRe-download JWK from toolkit
CORS errorsFrontend/backend port mismatchEnsure both are running on configured ports
Docker pull unauthorizedAuthentication requiredLog in to GitHub Container Registry: docker login ghcr.io -u YOUR_GITHUB_USERNAME
Docker container won't startPort conflictStop other services on ports 8000/9000 or use different ports

Next Steps​

After validating your integration locally:

  1. Contact your PM - Request QA environment access.
  2. Complete the Setup Checklist - Provide application details.
  3. Begin QA testing - Validate with real Candescent endpoints.
  4. Proceed to certification - Complete FI environment testing.

References​